前言

一連好幾天撰寫使用 VS Code 開發前端三劍客，是時候脫離一下前端的世界，來點輕鬆的內容吧！

身為一位工程師，一定會接觸 Markdown（如果沒有接觸，你是不是沒幫專案寫 README.md？），而 VS Code 本身內建支援 Markdown，因此，不需要安裝特別的 Extension，就可以直接使用。

以下整理使用 VS Code 撰寫 Markdown 的小知識。

前提

這篇的內容是如何加速撰寫 Markdown，如果正在閱讀的你尚未熟悉 Markdown 的語法，以下整理幾個網站，讓你可以趕緊上手。

• iT邦。
  • 參加鐵人賽，最高順位的說明文當然是 iT幫
• 前端工具百寶箱 - 六角學院。
  • 去年六角學院的優文之一，這篇寫的淺顯易懂。
• Git Book 教學。
  • 筆者剛學習使用 Markdown 時，最常閱讀的說明文，提供大量的示範讓筆者可以快速了解輸出的結果長什麼樣子。
• Markdown Syntax。
  • 官方文件的正體中文版，內容肯定是最仔細的，所以在閱讀上非常不容易進入狀況，建議撰寫一段時間後，想要精進的人閱讀。

如何使用

文件預覽

VS Code 已經內建預覽模式了，啟用預覽的方式很簡單：

• 開啟 .md 檔。
• 將滑鼠移動到右上角，點擊：
  • 
• 會在右側開啟預覽畫面：
  • 

在預覽的狀態時：

• 編輯區塊有任何更動，預覽畫面將會馬上更新，達到即時性。
• 不論是在編輯區塊或是預覽區塊，滾動滑鼠的滾論，會兩個區塊會同步滾動。

大綱預覽

活動列選擇檔案總管，將滑鼠移動到最下方的大綱區，點擊後就可以看到了

關於安全性

VS Code 預設任何外部資源，開頭必須是 https，如果是 http，則在文件預覽的時候，將會無法顯示。

如果想要調整，步驟如下：

• 按下 F1。
• 輸入 >markdown change preview security setting。
• 選擇符合自己需求的選項。
  • 

Extension

最推薦頭兩個

markdownlint

連結

使用上要注意兩點：

• 了解 Lint 警告什麼，步驟如下：
  • 注意 Lint 提醒不合語法的地方，滑鼠移動過去，等待解說框框出現。
  • 點擊快速修復。
    • 
  • 點擊 Click for more information about MDxxx/oooo。
    • 
• 警告的內容不符合自己的使用需求，那就關掉，步驟如下：
  • 滑鼠移到左下角，點擊齒輪。
    • 
  • 點擊設定。
  • 滑鼠移動到右上角，點擊開啟設定（JSON）。
    • 
  • 找尋 markdownlint.config，將想要關掉的警告取消掉：

// 範例
{
  "markdownlint.config": {
    "MD024": false,
  },
}

Markdown All in One

連結

如名稱所言，All in One，提供的功能有：

• 快捷鍵，例如：粗體、斜體。
• 撰寫 list 時，按下 enter 會自動補 *。
• 將 .md 檔案，轉換成 .html，步驟如下：
  • 按下 F1。
  • 輸入 Markdown: Print current document to HTML。
  • .md 所屬的資料夾，會產生一樣名稱，副檔名是 .html 的轉換檔。
• 排版，按法如下：
  • Windows: Ctrl + Shift + F。
  • macOS: Option + Shift + F。
  • Linux: Ctrl + Shift + I。
• 數學符號、算式支援。
• 類似 IntelliSense 的支援：
  • 圖片路徑自動完成。
  • 網址路徑自動完成。
  • 數學函式。

當然，如果不喜歡 All in One，可以下載自己需要的。

預覽 Style

如果不喜歡 VS Code 預設的，有兩款可以改變：

• Markdown Preview Github Styling。
• Markdown Preview with Bitbucket Styles。

強化預覽

VS Code 預設的預覽，不會支持全部的語法，例如：

• 數學符號、算式。
  • Markdown+Math。
• Mermaid 流程圖。
  • Markdown Preview Mermaid Support。
• 兩者都包含的整合包：
  • Markdown Preview Enhanced。

此外，顏文字（Emoji）在預設中沒有支援，需要下載 Extension：

• Markdown Emoji。

小工具

• Markdown Table Prettifier。
  • 人工撰寫表格，往往語法上醜不堪言，這款 Extension 可以自動排版。

轉換成 .pdf、.html

這邊提供兩個：

• Markdown PDF。
  • 安裝要非常久
  • 步驟如下：
    • 按下 F1。
    • 輸入 export。
    • 選擇要輸出的檔案格式。
• Markdown Converter。
  • 步驟如下：
    • 開啟設定的 .json，詳細的進入方式，請參考今天的段落：markdownlint。
    • 新增設定（請參考下方）
    • 按下 F1。
    • 輸入 Markdown: Convert。
    • 選擇要輸出一份還是全部 .md。

// 新增設定
{
  "markdownConverter.ConversionType": [
    "HTML",
    "PDF"
  ],
  "markdownConverter.DestinationPattern": "${workspaceFolder}/output/${dirname}/${basename}.${extension}"
}

關於以上兩個插件的作法，推測如下：

• 先轉換成 .html。
• 下載 Chromium。
• 使用 Chromium 將 .html 轉換成 .pdf。

結論

今天介紹如何使用 VS Code 加速撰寫 Markdown，身為一位工程師，能夠加速撰寫，肯定能感到開心的。

善用這些工具，讓自己每次撰寫文件事的時候，盡可能減少不開心的部分！